Node / meshtastic / Meshtastic-Android / files / .github / agents / speckit.clarify.agent.md

Displaying Raw • View rendered • Download

---

description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.

handoffs:

Tff7b72- label: Build Technical Plan

agent: speckit.plan

Tc9d1d9 prompt: Create a plan for the spec. I am building with...

Tc9d1d9---

Tc9d1d9## User Input

Ta5d6ff```Ta5d6fftext

$ARGUMENTS

Ta5d6ff```

You **MUST** consider the user input before proceeding (if not empty).

Tc9d1d9## Pre-Execution Checks

**Check for extension hooks (before clarification)**:

Tff7b72- Check if Ta5d6ff`.specify/extensions.yml` exists in the project root.

Tff7b72- If it exists, read it and look for entries under the Ta5d6ff`hooks.before_clarify` key

Tff7b72- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

Tff7b72- Filter out hooks where Ta5d6ff`enabled` is explicitly Ta5d6ff`false`. Treat hooks without an Ta5d6ff`enabled` field as enabled by default.

Tff7b72- For each remaining hook, do **not** attempt to interpret or evaluate hook Ta5d6ff`condition` expressions:

Tff7b72- If the hook has no Ta5d6ff`condition` field, or it is null/empty, treat the hook as executable

Tff7b72- If the hook defines a non-empty Ta5d6ff`condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

Tff7b72- For each executable hook, output the following based on its Ta5d6ff`optional` flag:

Tff7b72- **Optional hook** (Ta5d6ff`optional: true`):

Ta5d6ff ```

## Extension Hooks

**Optional Pre-Hook**: {extension}

Command: `/{command}`

Description: {description}

Prompt: {prompt}

To execute: `/{command}`

```

Tff7b72- **Mandatory hook** (Ta5d6ff`optional: false`):

Ta5d6ff ```

## Extension Hooks

**Automatic Pre-Hook**: {extension}

Executing: `/{command}`

EXECUTE_COMMAND: {command}

Wait for the result of the hook command before proceeding to the Outline.

```

Tff7b72- If no hooks are registered or Ta5d6ff`.specify/extensions.yml` does not exist, skip silently

Tc9d1d9## Outline

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking Ta5d6ff`/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

Tff7b721. Run Ta5d6ff`.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined Ta5d6ff`--json --paths-only` mode / Ta5d6ff`-Json -PathsOnly`). Parse minimal JSON payload fields:

Tff7b72- Ta5d6ff`FEATURE_DIR`

Tff7b72- Ta5d6ff`FEATURE_SPEC`

Tff7b72- (Optionally capture Ta5d6ff`IMPL_PLAN`, Ta5d6ff`TASKS` for future chained flows.)

Tff7b72- If JSON parsing fails, abort and instruct user to re-run Ta5d6ff`/speckit.specify` or verify feature branch environment.

Tff7b72- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

Tff7b722. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

Functional Scope & Behavior:

Tff7b72- Core user goals & success criteria

Tff7b72- Explicit out-of-scope declarations

Tff7b72- User roles / personas differentiation

Domain & Data Model:

Tff7b72- Entities, attributes, relationships

Tff7b72- Identity & uniqueness rules

Tff7b72- Lifecycle/state transitions

Tff7b72- Data volume / scale assumptions

Interaction & UX Flow:

Tff7b72- Critical user journeys / sequences

Tff7b72- Error/empty/loading states

Tff7b72- Accessibility or localization notes

Non-Functional Quality Attributes:

Tff7b72- Performance (latency, throughput targets)

Tff7b72- Scalability (horizontal/vertical, limits)

Tff7b72- Reliability & availability (uptime, recovery expectations)

Tff7b72- Observability (logging, metrics, tracing signals)

Tff7b72- Security & privacy (authN/Z, data protection, threat assumptions)

Tff7b72- Compliance / regulatory constraints (if any)

Integration & External Dependencies:

Tff7b72- External services/APIs and failure modes

Tff7b72- Data import/export formats

Tff7b72- Protocol/versioning assumptions

Edge Cases & Failure Handling:

Tff7b72- Negative scenarios

Tff7b72- Rate limiting / throttling

Tff7b72- Conflict resolution (e.g., concurrent edits)

Constraints & Tradeoffs:

Tff7b72- Technical constraints (language, storage, hosting)

Tff7b72- Explicit tradeoffs or rejected alternatives

Terminology & Consistency:

Tff7b72- Canonical glossary terms

Tff7b72- Avoided synonyms / deprecated terms

Completion Signals:

Tff7b72- Acceptance criteria testability

Tff7b72- Measurable Definition of Done style indicators

Misc / Placeholders:

Tff7b72- TODO markers / unresolved decisions

Tff7b72- Ambiguous adjectives ("robust", "intuitive") lacking quantification

For each category with Partial or Missing status, add a candidate question opportunity unless:

Tff7b72- Clarification would not materially change implementation or validation strategy

Tff7b72- Information is better deferred to planning phase (note internally)

Tff7b723. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

Tff7b72- Maximum of 5 total questions across the whole session.

Tff7b72- Each question must be answerable with EITHER:

Tff7b72- A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR

Tff7b72- A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").

Tff7b72- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.

Tff7b72- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.

Tff7b72- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).

Tff7b72- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.

Tff7b72- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

Tff7b724. Sequential questioning loop (interactive):

Tff7b72- Present EXACTLY ONE question at a time.

Tff7b72- For multiple‑choice questions:

Tff7b72- **Analyze all options** and determine the **most suitable option** based on:

Tff7b72- Best practices for the project type

Tff7b72- Common patterns in similar implementations

Tff7b72- Risk reduction (security, performance, maintainability)

Tff7b72- Alignment with any explicit project goals or constraints visible in the spec

Tff7b72- Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).

Tff7b72- Format as: Ta5d6ff`**Recommended:** Option [X] - <reasoning>`

Tff7b72- Then render all options as a Markdown table:

| Option | Description |

|--------|-------------|

| A | <Option A description> |

| B | <Option B description> |

| C | <Option C description> (add D/E as needed up to 5) |

| Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |

Tff7b72- After the table, add: Ta5d6ff`You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`

Tff7b72- For short‑answer style (no meaningful discrete options):

Tff7b72- Provide your **suggested answer** based on best practices and context.

Tff7b72- Format as: Ta5d6ff`**Suggested:** <your proposed answer> - <brief reasoning>`

Tff7b72- Then output: Ta5d6ff`Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`

Tff7b72- After the user answers:

Tff7b72- If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.

Tff7b72- Otherwise, validate the answer maps to one option or fits the <=5 word constraint.

Tff7b72- If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).

Tff7b72- Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.

Tff7b72- Stop asking further questions when:

Tff7b72- All critical ambiguities resolved early (remaining queued items become unnecessary), OR

Tff7b72- User signals completion ("done", "good", "no more"), OR

Tff7b72- You reach 5 asked questions.

Tff7b72- Never reveal future queued questions in advance.

Tff7b72- If no valid questions exist at start, immediately report no critical ambiguities.

Tff7b725. Integration after EACH accepted answer (incremental update approach):

Tff7b72- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.

Tff7b72- For the first integrated answer in this session:

Tff7b72- Ensure a Ta5d6ff`## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).

Tff7b72- Under it, create (if not present) a Ta5d6ff`### Session YYYY-MM-DD` subheading for today.

Tff7b72- Append a bullet line immediately after acceptance: Ta5d6ff`- Q: <question> → A: <final answer>`.

Tff7b72- Then immediately apply the clarification to the most appropriate section(s):

Tff7b72- Functional ambiguity → Update or add a bullet in Functional Requirements.

Tff7b72- User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.

Tff7b72- Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.

Tff7b72- Non-functional constraint → Add/modify measurable criteria in Success Criteria > Measurable Outcomes (convert vague adjective to metric or explicit target).

Tff7b72- Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).

Tff7b72- Terminology conflict → Normalize term across spec; retain original only if necessary by adding Ta5d6ff`(formerly referred to as "X")` once.

Tff7b72- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.

Tff7b72- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).

Tff7b72- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.

Tff7b72- Keep each inserted clarification minimal and testable (avoid narrative drift).

Tff7b726. Validation (performed after EACH write plus final pass):

Tff7b72- Clarifications session contains exactly one bullet per accepted answer (no duplicates).

Tff7b72- Total asked (accepted) questions ≤ 5.

Tff7b72- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.

Tff7b72- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).

Tff7b72- Markdown structure valid; only allowed new headings: Ta5d6ff`## Clarifications`, Ta5d6ff`### Session YYYY-MM-DD`.

Tff7b72- Terminology consistency: same canonical term used across all updated sections.

Tff7b727. Write the updated spec back to Ta5d6ff`FEATURE_SPEC`.

Tff7b728. Report completion (after questioning loop ends or early termination):

Tff7b72- Number of questions asked & answered.

Tff7b72- Path to updated spec.

Tff7b72- Sections touched (list names).

Tff7b72- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).

Tff7b72- If any Outstanding or Deferred remain, recommend whether to proceed to Ta5d6ff`/speckit.plan` or run Ta5d6ff`/speckit.clarify` again later post-plan.

Tff7b72- Suggested next command.

Behavior rules:

Tff7b72- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.

Tff7b72- If spec file missing, instruct user to run Ta5d6ff`/speckit.specify` first (do not create a new spec here).

Tff7b72- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).

Tff7b72- Avoid speculative tech stack questions unless the absence blocks functional clarity.

Tff7b72- Respect user early termination signals ("stop", "done", "proceed").

Tff7b72- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.

Tff7b72- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: $ARGUMENTS

Tc9d1d9## Post-Execution Checks

**Check for extension hooks (after clarification)**:

Check if Ta5d6ff`.specify/extensions.yml` exists in the project root.

Tff7b72- If it exists, read it and look for entries under the Ta5d6ff`hooks.after_clarify` key

Tff7b72- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally

Tff7b72- Filter out hooks where Ta5d6ff`enabled` is explicitly Ta5d6ff`false`. Treat hooks without an Ta5d6ff`enabled` field as enabled by default.

Tff7b72- For each remaining hook, do **not** attempt to interpret or evaluate hook Ta5d6ff`condition` expressions:

Tff7b72- If the hook has no Ta5d6ff`condition` field, or it is null/empty, treat the hook as executable

Tff7b72- If the hook defines a non-empty Ta5d6ff`condition`, skip the hook and leave condition evaluation to the HookExecutor implementation

Tff7b72- For each executable hook, output the following based on its Ta5d6ff`optional` flag:

Tff7b72- **Optional hook** (Ta5d6ff`optional: true`):

Ta5d6ff ```

## Extension Hooks

**Optional Hook**: {extension}

Command: `/{command}`

Description: {description}

Prompt: {prompt}

To execute: `/{command}`

```

Tff7b72- **Mandatory hook** (Ta5d6ff`optional: false`):

Ta5d6ff ```

## Extension Hooks

**Automatic Hook**: {extension}

Executing: `/{command}`

EXECUTE_COMMAND: {command}

```

Tff7b72- If no hooks are registered or Ta5d6ff`.specify/extensions.yml` does not exist, skip silently